Star Wars Fanon:API
This is a documentation of the Wookieepedia reusable JavaScript file (MediaWiki:Functions.js). This file is site-independent and can be used on any Wikia wiki. Bootstrapping * Copy MediaWiki:Functions.js to your wiki. * Add the following to your MediaWiki:Common.js: importScript('MediaWiki:Functions.js'); * Add the following call to your first onload hook: initFunctionsJS(); Why isn't feature X present? It contains code that is or was once used in Wookieepedia's Monobook.js/Common.js, refactored to be reusable. Nothing more, nothing less. Classes ContentLoader Used by: requestComboFill, doPreload This class encapsulates different implementations of XMLHttpRequest, hiding their complexities behind a (slightly) simpler API. The primary purpose of the ContentLoader class is to fetch web pages as text (either HTML text or wikitext, which can be obtained on MediaWiki by adding the "action=raw" parameter). It can be also used to do POST requests, although on MediaWiki the usefulness of this feature is dubious. Subject to the Same Origin Policy, which is hardcoded in modern web browsers (can only be used on the same wiki/subdomain, not across Wikia). Even though slightly more high-level than XMLHttpRequest, it's still fairly low-level and should only be used by advanced users. Constructor constructor ContentLoader(); Creates a new ContentLoader object. Public fields get boolean cache; Specifies whether caching is enabled. Default: true. set function() callback; The function that gets called after the data arrive from the HTTP server. When it is called, "this" is the ContentLoader object. State can be stored and retrieved using its global fields. Usually, the code that sends the request creates new fields in the ContentLoader object to store the state, which is then retrieved in the callback. get string text; Used in the callback function to retrieve the HTML code or plaintext of the retrieved page. get Document document; Used in the callback function as the root element of the DOM tree if the retrieved page is an XML document. Public methods void enableCache(boolean cache = true); Enables or disables caching. If the user calls this method, it must be done before send(). void send(string url, string postdata = null, string contentType = 'application/x-www-form-urlencoded'); Sends an HTTP request to the server and immediately returns without waiting for it to complete. When the request arrives, the callback function will be called. If postdata is null, a GET request is sent. Otherwise, a POST request is sent with the content type set per the contentType parameter. The "url" parameter can be either an absolute address (http://starwars.wikia.com/index.php?...) or a relative address (/index.php?...). The relative form is preferred for the sake of portability. ClassTester Used by: getElementsByClass, getParentByClass Tests HTML DOM elements, determining if they belong to the specified CSS class. Constructor constructor ClassTester(string className); Creates a new ClassTester object testing for a specific class name. Public methods boolean isMatch(Element e); Returns a value indicating if the specified DOM element belongs to the CSS class. Standard object enhancements string String::trim(); Used by: (indirectly) window.pageName; Removes whitespace from the beginning and end of a string and returns the result. Global variables get boolean window.storagePresent; If this variable is set to true, the browser supports the globalStorage object. Equivalent to (typeof(globalStorage) != 'undefined'). As of this writing, only Firefox 2.0+ supports the globalStorage object. get string window.pageName; Depends on: getFirstHeading, (indirectly) String::trim; Contains the pagename, as it was before any title modifications took place. (This means initFunctionsJS() needs to be called before any title manipulation.) Functions Array manipulation int arrayFind(mixed[] array, mixed value); Searches an array for an element and returns its index, or -1 if it's not in the array. void arrayRemove(mixed[] array, mixed value); Removes the first occurrence of an element in an array, if it is there. DOM manipulation Element[] getElementsByClass(string className, Element e = document, string tag = '*'); Used by: getFirstHeading, substUsername, rewriteHover Depends on: ClassTester Returns an array of all DOM elements that are (direct or indirect) children of a given DOM element and have the specified CSS class. The search can be limited to a specific tag name. If no tag name is given, it searches for any suitable elements regardless of the tag name. Element getParentByClass(string className, Element e); Depends on: ClassTester Returns the "nearest" parent element of a given DOM element that has the specified CSS class. If no such element is found all the way to the DOM root, returns null. HTML/URL helpers void insertAtCursor(HTMLTextArea field, string text); Used by: (indirectly) doPreload Inserts text into the cursor position at the given textarea DOM element. If the browser doesn't support this, it falls back to adding the new text at the end of the textarea content. string queryString(string key); Returns the parameter as it appears in the query string (URL). Resembles $_GETkey in PHP. Example: if the request is /index.php?title=Main_Page&action=edit, queryString('title') returns 'Main_Page', and queryString('action') returns 'edit'. Wiki-specific functions Element getFirstHeading(); Depends on: getElementsByClass Returns the h1.firstHeading element (the header element that contains the page name). void requestComboFill(string comboID, string pageName); Depends on: ContentLoader Retrieves the wikitext of the specified page (on the same wiki) and fills the specified (by id) combo box with it. The page must be of the same format as wikia:starwars:Template:Stdsummaries, and must not be in the MediaWiki namespace. void doPreload(string pageName); Depends on: ContentLoader, (indirectly) insertAtCursor Retrieves the wikitext of the specified page and inserts it into the edit box at the cursor position. void rewriteSearchFormLink(); Makes the link associated with File:Search logo.png in the search box (if it is uploaded) point to the wiki's search page instead of Wikia. void substUsername(); Depends on: getElementsByClass Inserts the name of the user viewing the page into span.insertusername. wikia:starwars:Template:USERNAME can be copied to the wiki for convenience and used (without parameters) where the username needs to be inserted. void rewriteHover(); Depends on: getElementsByClass Adds an onmousehover handler to all #hover-global .hoverable elements. This handler adds the CSS class "over" to an element when the mouse is over it and removes it when the mouse leaves it. It is essentially a workaround for the IE6 :hover bug (:hover CSS declarations are not respected for anything but links). CSS maintainers are requested to use both element:hover and element.over in the same declaration, as a fallback for non-JavaScript-enabled clients (except IE6; in non-JavaScript-enabled IE6, none of these declarations will work).